<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>MRtrix documentation</title>
<link rel="stylesheet" href="../stylesheet.css" type="text/css" media=screen>
</head>
<body>

<table class=nav>
  <tr>
    <td><a href="overview.html"><img src="../left.png"></a></td>
    <td><a href="index.html"><img src="../up.png"></a></td>
    <td><a href="../index.html"><img src="../home.png"></a></td>
    <th>Command-line Usage</th>
    <td><a href="formats.html"><img src="../right.png"></a></td>
  </tr>
</table>

<h2><a name="basicusage">Basic usage</a></h2>
<p>
Commands are generally issued by typing the <em>command name</em>, followed by a series of <em>arguments</em> and <em>options</em> separated by white spaces. 
MRtrix applications will typically require at least one <em>argument</em> (usually an image specifier), 
and may need to be tuned in some way using command line options (described <a href='#options'>here</a>).
</p>
<p>
Consider the <kbd><a href='../commands/mrconvert.html'>mrconvert</a></kbd> command:
</p>
<pre>
&gt; <b><a href='../commands/mrconvert.html'>mrconvert</a> image.img -vox 1,1,2.5 out.mif</b>
<a href='../commands/mrconvert.html'>mrconvert</a>: copying data... 100%
</pre>
<p>
In this example, <kbd><a href='../commands/mrconvert.html'>mrconvert</a></kbd> is the command name, <kbd>image.img</kbd> is the first argument, 
<kbd>out.mif</kbd> is the second argument, <kbd>-vox</kbd> is an option, 
and <kbd>1,1,2.5</kbd> is an additional argument required by the <kbd>-vox</kbd> option. 
This command converts the Analyse format image <kbd>image.img</kbd> into the MRtrix format image <kbd>out.mif</kbd>,
overriding the original voxel size to 1 &times; 1 &times; 2.5 mm.
</p>
<p>
In order to find out how to use a particular program, you can use the <kbd>-help</kbd> option 
to display that program's help page (see <a href='#stdoptions'>Standard options</a>).
</p>
<p>
Note that since arguments are assumed to be separated by white space,
filenames containing a space need to be treated with special care to avoid them being interpreted as two arguments instead of one. 
There are several ways to avoid this problem: 
the filename can be enclosed in inverted commas, or each white space can be <em>escaped</em> with a preceeding backslash (<kbd>'\'</kbd>). 
For example, if there is a file named <kbd>'an example filename.img'</kbd>, 
then the following commands are all valid and equivalent:
</p>
<pre>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> 'an example filename.img'</b>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> "an example filename.img"</b>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> an\ example\ filename.img</b>
</pre>
<p>
Unix only: note also that commands and filenames are case-sensitive. If a command you issued fails, check its spelling and case.
</p>


<p class=sep><a href="#top">top</a></p>



<h2><a name="options">Command line options</a></h2>
<p>
Command line options may be supplied to modify the behaviour of a program, or to supply additional information. 
A command-line option consists of one or more minus signs immediately followed by the option name. 
Options will often require additional arguments to operate correctly, in which case these must be specified immediately after the option itself.
</p>
<p>
The following example illustrates an option modifying the behaviour of a program:
</p>
<pre>
&gt; <b><a href='../commands/mrconvert.html'>mrconvert</a> -info /data/DICOM_folder/ out.img</b>
<a href='../commands/mrconvert.html'>mrconvert</a> [INFO]: opening image "/data/DICOM_folder/"...
<a href='../commands/mrconvert.html'>mrconvert</a> [INFO]: initialising DICOM dictionary
<a href='../commands/mrconvert.html'>mrconvert</a>: scanning DICOM folder /data/DICOM_folder/"  - ok
<a href='../commands/mrconvert.html'>mrconvert</a>: reading DICOM series "t1_mpr_0.9 iso hres"... 100%
<a href='../commands/mrconvert.html'>mrconvert</a> [INFO]: loading image "VOLUNTEER(000366) [MR] t1_mpr_0.9 iso hres"...
<a href='../commands/mrconvert.html'>mrconvert</a> [INFO]: creating image "poo.mif"...
<a href='../commands/mrconvert.html'>mrconvert</a>: copying data... 100%
<a href='../commands/mrconvert.html'>mrconvert</a> [INFO]: closing image "VOLUNTEER(000366) [MR] t1_mpr_0.9 iso hres"...
<a href='../commands/mrconvert.html'>mrconvert</a> [INFO]: closing image "./poo.mif"...
</pre>
<p>
In this example, the <kbd>-info</kbd> option tells the program to display additional information while processing. 
</p>
<p>
The following example illustrates the case of an option requiring an additional argument to specify additional information:
</p>
<pre>
&gt; <b><a href='../commands/threshold.html'>threshold</a> image.img -percent 20 -invert mask.img</b>
<a href='../commands/threshold.html'>threshold</a>: finding min/max... 100%
<a href='../commands/threshold.html'>threshold</a>: thresholding at intensity 266.8... 100%
</pre>
<p>
In this example, the <kbd>-percent</kbd> option tells the <kbd><a href='../commands/threshold.html'>threshold</a></kbd> program 
to threshold at the 20% level, and the <kbd>-invert</kbd> option causes it to invert the results. 
This will produce the binary mask image <kbd>mask.img</kbd>,
where pixels are set to one if the original intensities were less than 20% of the maximum pixel intensity in <kbd>image.img</kbd>,
and set to zero otherwise.
</p>
<p>
MRtrix programs will accept shortened option names as long as there are no ambiguities.
For example, the following command is equivalent to that above:
</p>
<pre>
&gt; <b><a href='../commands/threshold.html'>threshold</a> image.img --p 20 -inv mask.img</b>
<a href='../commands/threshold.html'>threshold</a>: finding min/max... 100%
<a href='../commands/threshold.html'>threshold</a>: thresholding at intensity 266.8... 100%
</pre>
<p>
However, the following command will fail:
</p>
<pre>
&gt; <b><a href='../commands/threshold.html'>threshold</a> image.img -p 20 -i mask.img</b>
<a href='../commands/threshold.html'>threshold</a>: several matches possible for option "i": "invert", "info"
</pre>
<p>
since <kbd><a href='../commands/threshold.html'>threshold</a></kbd> accepts two different options that both start with 'i'.
</p>


<p class=sep><a href="#top">top</a></p>



<h2><a name="stdoptions">Standard options</a></h2>
<p>
All MRtrix programs understand the following options:
</p>
<table width=80%>
<tr><th>Option</th><th>Action</th></tr> 
  <tr><td nowrap><kbd>-info</kbd></td><td>display information messages.</td></tr>
  <tr><td nowrap><kbd>-quiet</kbd></td><td>do not display information messages or progress status.</td></tr>
  <tr><td nowrap><kbd>-debug</kbd></td><td>display debugging messages.</td></tr>
  <tr><td nowrap><kbd>-help</kbd></td><td>display the program's information page and exit.</td></tr>
  <tr><td nowrap><kbd>-version</kbd></td><td>display version information and exit.</td></tr>
</table>

<p>
To find out how to use a program, including the required number of arguments and all valid options,
type the program name followed by the <kbd>-help</kbd> option. This will display that program's help page.
</p>





<p class=sep><a href="#top">top</a></p>

<h2><a name="sequences">Number sequences</a></h2>
<p>
Many MRtrix applications understand <em>sequences</em> of numbers and can operate according to the sequence specified. 
For example, you may only need a few series from a data set.
In this case, you could use the <kbd><a href='../commands/mrconvert.html'>mrconvert</a></kbd> command and specify the series you need as follows:
<p>
<pre>
&gt; <b><a href='../commands/mrconvert.html'>mrconvert</a> -coord 3 0:3,8,10 dwi.mif dwi-[].img</b>
</pre>
<p>
In this example, <kbd><a href='../commands/mrconvert.html'>mrconvert</a></kbd> will select from the image data set <kbd>dwi.mif</kbd>
the series specified by the number sequence <kbd>0:3,8,10</kbd>,
corresponding to the numbers 0, 1, 2, 3, 8 &amp; 10
(this assumes that the series axis is axis 3).
The output images will be stored as a set of numbered Analyse format images, named <kbd>dwi-0.img</kbd>, <kbd>dwi-1.img</kbd>, etc.
(the 'square brackets' syntax used here is explained below).
</p>
<p>
Note that a number sequence cannot contain any spaces, since it would then be interpreted as two arguments (see <a href='#basicusage'>Basic usage</a>). 
The syntax consists of a comma-separated list of any of the following items:
</p>
<dl>
<dt>a</dt>
<dd>the integer <b>a</b>.</dd>

<dt>a:b</dt>
<dd>
all integers from <b>a</b> to <b>b</b> inclusive.<br>
If <b>a</b> is greater than <b>b</b>, then the sequence will run down from <b>a</b> to <b>b</b>.<br>
The keyword <kbd>end</kbd> may be used instead of either <kbd>a</kbd> or <kbd>b</kbd> in certain cases where its meaning is unambiguous.
</dd>

<dt>a:i:b</dt>
<dd>
the integers <b>a</b>, <b>a+i</b>, <b>a+2i</b>, ..., <b>b</b>.<br>
The sign of <b>i</b> will be set according to the relative magnitudes of <b>a</b> and <b>b</b> to ensure that the sequence is valid.<br>
</dd>
</dl>
<p>
The square brackets used in the example above (<kbd>dwi-[].img</kbd>) are used to indicate a numbered sequence of images
that should be interpreted as a single data set (e.g. a fMRI time series). 
In the previous case, the sequence was left empty, leaving the program to automatically number the filenames accordingly.
These images can be accessed using a similar syntax. For example:
</p>
<pre>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> dwi-[].img</b>
</pre>
<p>
will access all matching images as a 4-dimensional data set (assuming each of the individual images contains a 3D data set).
If only one of the images is of interest, it can be accessed by specifying its filename as normal without the use of square brackets:
</p>
<pre>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> dwi-1.img</b>
</pre>
<p>
Finally, to access a data set formed from a subset of the images, insert the appropriate number sequence within the square brackets:
</p>
<pre>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> dwi-[1,3].img</b>
</pre>
<p>
Note that when using number sequences to specify a filename, any leading zeros in the number field will be ignored.
For example, the images <kbd>dwi-1.img</kbd> and <kbd>dwi-001.img</kbd> will both be matched by the identifier <kbd>dwi-[1].img</kbd>.
</p>





<p class=sep><a href="#top">top</a></p>

<h2><a name="pipes">Data pipes</a></h2>
<p>
The output of one program can be fed straight through to the input of another program via <em>pipes</em> in a single command. 
The appropriate syntax is illustrated in this example:
</p>
<pre>
&gt; <b><a href='../commands/dwi2tensor.html'>dwi2tensor</a> /data/DICOM_folder/ - | tensor2vector - ev.mif</b>
<a href='../commands/dwi2tensor.html'>dwi2tensor</a>: scanning DICOM folder "/data/DICOM_folder/"  - ok
<a href='../commands/dwi2tensor.html'>dwi2tensor</a>: reading DICOM series "diff60_b3000_2.3_iPat2+ADC"... 100%
<a href='../commands/dwi2tensor.html'>dwi2tensor</a>: DICOM image contains mosaic files - reformating... 100%
<a href='../commands/dwi2tensor.html'>dwi2tensor</a>: converting DW images to tensor image... 100%
<a href='../commands/tensor2vector.html'>tensor2vector</a>: generating major eigenvector map... 100%
</pre>
<p>
This command will execute the following actions:
</p>
<ol>
  <li><kbd><a href='../commands/dwi2tensor.html'>dwi2tensor</a></kbd> will load 
  the input diffusion-weighted data in DICOM format from the folder <kbd>/data/DICOM_folder/</kbd>
  and compute the corresponding tensor components. The resulting data set is then fed into the pipe.</li>
  <li><kbd><a href='../commands/tensor2vector.html'>tensor2vector</a></kbd> will access the data set from the pipe, 
  generate an eigenvector map and store the resulting data set as <kbd>ev.mif</kbd>.
</ol>
<p>
The two stages of the pipeline are separated by the <kbd>'|'</kbd> symbol, which indicates to the system that the output of the first command
is to be used as input for the next command. The image that is to be fed to or from the pipeline is specified for each program using a single dash <kbd>'-'</kbd>
where the image would normally be specified as an argument.
</p>
<p>
For this work properly, it is important to know which arguments each program will interpret as <em>input</em> images,
and which as <em>output</em> images. For example, this command will fail:
</p>
<pre>
&gt; <b><a href='../commands/dwi2tensor.html'>dwi2tensor</a> - /data/DICOM_folder/ | <a href='../commands/tensor2vector.html'>tensor2vector</a> - ev.mif</b>
</pre>
<p>
In this example, <kbd><a href='../commands/dwi2tensor.html'>dwi2tensor</a></kbd> will hang waiting for input data (its first argument should be the input DWI data set).
This will also cause <kbd><a href='../commands/tensor2vector.html'>tensor2vector</a></kbd> to hang 
while it waits for <kbd><a href='../commands/dwi2tensor.html'>dwi2tensor</a></kbd> to provide some input.
</p>
<h3>Advanced</h3>
<p>
The procedure used in MRtrix to feed data sets down a pipeline is somewhat different from the more traditional use of pipes.
Given the large amounts of data typically contained in a data set, the 'standard' practice of feeding the data through the pipe
would be prohibitively inefficient. MRtrix applications access the data via <em>memory-mapping</em> (when this is possible), 
and do not need to explicitly copy the data into their own memory space. When using pipes, MRtrix applications will simply generate 
a temporary file and feed its <em>filename</em> through to the next stage once their processing is done. 
The next program in the pipeline will then simply read this filename and access the corresponding file. 
The latter program is then responsible for deleting the temporary file once its processing is done.
</p>
<p>
This implies that any errors during processing may result in undeleted temporary files.
These will normally be created within the current directory with a filename of the form <kbd>mrtrix-XXXXXX.xyz</kbd>.
If a piped command has failed, and no other MRtrix programs are currently running, these can be safely deleted.
</p>
<p>
Such pipelines are not limited to two programs. Complex operations can be perfomed in one command using this technique. 
Here is a longer example:
</p>
<pre>
&gt; <b><a href='../commands/dwi2tensor.html'>dwi2tensor</a> /data/DICOM_folder/ - | <a href='../commands/tensor2vector.html'>tensor2vector</a> - - | <a href='../commands/mrmult.html'>mrmult</a> - mask.img - | <a href='../commands/mrview.html'>mrview</a> -</b>
<a href='../commands/dwi2tensor.html'>dwi2tensor</a>: scanning DICOM folder "/data/DICOM_folder/"  - ok
<a href='../commands/dwi2tensor.html'>dwi2tensor</a>: reading DICOM series "diff60_b3000_2.3_iPat2+ADC"... 100%
<a href='../commands/dwi2tensor.html'>dwi2tensor</a>: DICOM image contains mosaic files - reformating... 100%
<a href='../commands/dwi2tensor.html'>dwi2tensor</a>: converting DW images to tensor image... 100%
<a href='../commands/tensor2vector.html'>tensor2vector</a>: generating major eigenvector map... 100%
<a href='../commands/mrmult.html'>mrmult</a>: multiplying... 100%
</pre>
<p>
This command will execute the following actions:
</p>
<ol>
  <li><kbd><a href='../commands/dwi2tensor.html'>dwi2tensor</a></kbd> will load the input diffusion-weighted data in DICOM format from the folder <kbd>/data/DICOM_folder/</kbd>
and compute the corresponding tensor components. The resulting data set is then fed into the pipe.</li>
<li><kbd><a href='../commands/tensor2vector.html'>tensor2vector</a></kbd> will access the tensor data set from the pipe, generate an eigenvector map and feed the resulting data into the next stage of the pipeline.</li>
<li><kbd><a href='../commands/mrmult.html'>mrmult</a></kbd> will access the eigenvector data set from the pipe, multiply it by the image <kbd>mask.img</kbd>, and feed the resulting data into the next stage of the pipeline.</li>
<li><kbd><a href='../commands/mrview.html'>mrview</a></kbd> will access the masked eigenvector data set from the pipe and display the resulting image.</li>
</ol>


<table class=nav>
  <tr>
    <td><a href="overview.html"><img src="../left.png"></a></td>
    <td><a href="index.html"><img src="../up.png"></a></td>
    <td><a href="../index.html"><img src="../home.png"></a></td>
    <th><a href='#top'>top</a></th>
    <td><a href="formats.html"><img src="../right.png"></a></td>
  </tr>
</table>

</body>
</html>


